<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.29
     from sysadmin.tnf on 19 December 2010 -->

<TITLE>Eli System Administration Guide - Odin Execution</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000" BACKGROUND="gifs/bg.gif">
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0" VALIGN=BOTTOM>
<TR VALIGN=BOTTOM>
<TD WIDTH="160" VALIGN=BOTTOM>
<A HREF="http://eli-project.sourceforge.net/">
<IMG SRC="gifs/elilogo.gif" BORDER=0>
</A>&nbsp;
</TD>
<TD WIDTH="25" VALIGN=BOTTOM>
<img src="gifs/empty.gif" WIDTH=25 HEIGHT=25>
</TD>
<TD ALIGN=LEFT WIDTH="475" VALIGN=BOTTOM>
<A HREF="index.html"><IMG SRC="gifs/title.png" BORDER=0></A>
</TD>
<!-- |DELETE FOR SOURCEFORGE LOGO|
<TD>
<a href="http://sourceforge.net/projects/eli-project">
<img
  src="http://sflogo.sourceforge.net/sflogo.php?group_id=70447&amp;type=13"
  width="120" height="30"
  alt="Get Eli: Translator Construction Made Easy at SourceForge.net.
    Fast, secure and Free Open Source software downloads"/>
</a>
</TD>
|DELETE FOR SOURCEFORGE LOGO| -->
</TR>
</TABLE>

<HR size=1 noshade width=785 align=left>
<TABLE BORDER=0 CELLSPACING=2 CELLPADDING=0>
<TR>
<TD VALIGN=TOP WIDTH="160">
<h4>General Information</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="index.html">Eli: Translator Construction Made Easy</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="gindex_1.html#SEC1">Global Index</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="faq_toc.html" >Frequently Asked Questions</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ee.html" >Typical Eli Usage Errors</a> </td></tr>
</table>

<h4>Tutorials</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="EliRefCard_toc.html">Quick Reference Card</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="novice_toc.html">Guide For new Eli Users</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="news_toc.html">Release Notes of Eli</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="nametutorial_toc.html">Tutorial on Name Analysis</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="typetutorial_toc.html">Tutorial on Type Analysis</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ee.html" >Typical Eli Usage Errors</a> </td></tr>
</table>

<h4>Reference Manuals</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ui_toc.html">User Interface</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="pp_toc.html">Eli products and parameters</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lidoref_toc.html">LIDO Reference Manual</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ee.html" >Typical Eli Usage Errors</a> </td></tr>
</table>

<h4>Libraries</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lib_toc.html">Eli library routines</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="modlib_toc.html">Specification Module Library</a></td></tr>
</table>

<h4>Translation Tasks</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lex_toc.html">Lexical analysis specification</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="syntax_toc.html">Syntactic Analysis Manual</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="comptrees_toc.html">Computation in Trees</a></td></tr>
</table>

<h4>Tools</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lcl_toc.html">LIGA Control Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="show_toc.html">Debugging Information for LIDO</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="gorto_toc.html">Graphical ORder TOol</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="fw_toc.html">FunnelWeb User's Manual</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ptg_toc.html">Pattern-based Text Generator</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="deftbl_toc.html">Property Definition Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="oil_toc.html">Operator Identification Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="tp_toc.html">Tree Grammar Specification Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="clp_toc.html">Command Line Processing</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="cola_toc.html">COLA Options Reference Manual</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="idem_toc.html">Generating Unparsing Code</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="mon_toc.html">Monitoring a Processor's Execution</a> </td></tr>
</table>

<h4>Administration</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="sysadmin_toc.html">System Administration Guide</a> </td></tr>
</table>

<HR WIDTH="100%">
<A HREF="mailto:eli-project-users@lists.sourceforge.net">
<IMG SRC="gifs/button_mail.gif" BORDER=0 ALIGN="left"></A>
<A HREF="index.html"><IMG SRC="gifs/home.gif" BORDER=0 ALIGN="right"></A>

</TD>
<TD VALIGN=TOP WIDTH="25"><img src="gifs/empty.gif" WIDTH=25 HEIGHT=25></TD>

<TD VALIGN=TOP WIDTH="600">
<H1>Eli System Administration Guide</H1>
<P>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="sysadmin_4.html"><IMG SRC="gifs/prev.gif" ALT="Previous Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="sysadmin_6.html"><IMG SRC="gifs/next.gif" ALT="Next Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="sysadmin_toc.html"><IMG SRC="gifs/up.gif" ALT="Table of Contents" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT="">
<HR size=1 noshade width=600 align=left>
<A NAME="IDX40"></A>
<A NAME="IDX41"></A>
<H1><A NAME="SEC15" HREF="sysadmin_toc.html#SEC15">Odin Execution</A></H1>
<P>
Odin is designed according to a client/server architecture.
The
<A NAME="IDX43"></A>
<A NAME="IDX42"></A>
server is responsible for maintaining the cache, and the
<A NAME="IDX45"></A>
<A NAME="IDX44"></A>
client is responsible for interacting with the user and
executing those tools not built into Odin.
Normally the client and the server run as separate processes,
possibly on different machines, communicating via network sockets.
<P>
<H2><A NAME="SEC16" HREF="sysadmin_toc.html#SEC16">Client execution</A></H2>
<P>
When you give an <CODE>eli</CODE> command, it starts an Odin client.
The client determines a specific cache from the command
(see  <A HREF="sysadmin_2.html#SEC5">Name of the cache</A>).
It then checks that cache to see whether a socket is associated with it.
If not, the client establishes a socket for the cache and forks
(see  <A HREF="sysadmin_5.html#SEC18">Interprocess communication</A>).
The forked process becomes the server for that cache, and listens for
clients on the socket.
<P>
The client connects to the server via the socket.
It continues to interact with you, accepting input and delivering reports.
Whenever you make a request, the client packages that request and forwards
it to the server.
If the server needs to invoke a tool that is not built into Odin, then it
sends an appropriate command line to the client to be executed.
<P>
Each client may have a colon-separated list of machines as the value of its
<A NAME="IDX46"></A>
<VAR>BuildHosts</VAR> variable
(see  <A HREF="ui_7.html#SEC17">Buildhosts Maxbuilds of Eli User Interface Reference Manual</A>).
The name <CODE>LOCAL</CODE> refers to the machine running the client;
it is assumed if no list is given.
The client executes the command line given it by the server on the first
machine in the list that does not have a currently executing command.
<P>
When the client terminates, either because you have responded to a prompt
with <KBD>C-d</KBD> or because the end of the input file has been reached in a
batch run, it informs the server of this termination.
<P>
<H2><A NAME="SEC17" HREF="sysadmin_toc.html#SEC17">Server execution</A></H2>
<P>
A server is associated with a specific cache.
The first client started on that cache creates the server by forking
(see  <A HREF="sysadmin_5.html#SEC16">Client execution</A>).
Subsequent clients started on that cache do not fork new servers, but
connect to the existing server via the socket already established for
the cache.
When all clients connected to the server have terminated,
the server itself terminates and closes the socket.
<P>
The server for a cache receives all requests involving that cache, and is
responsible for ensuring that requests involving specific files are
sequenced so that all requests are effectively atomic.
<P>
Tools built into Odin are also executed by the server.
If a client request requires execution of an external tool, the server
builds a command line invoking the tool and passes it to the first
client that is not currently executing such a command line.
Thus the server may involve a client in running tools necessary to
satisfy requests from other clients.
<P>
<H2><A NAME="SEC18" HREF="sysadmin_toc.html#SEC18">Interprocess communication</A></H2>
<A NAME="IDX47"></A>
<P>
When a client is started on a cache
(see  <A HREF="sysadmin_5.html#SEC16">Client execution</A>),
it checks whether the cache contains a file named
<A NAME="IDX49"></A>
<A NAME="IDX48"></A>
<TT>`SOCKET'</TT>.
<TT>`SOCKET'</TT> is normally a text file containing a single line giving the
name of the machine on which the server is running and the port number to
which it is listening
(but see  <A HREF="sysadmin_5.html#SEC20">Socket implementation</A>).
If <TT>`SOCKET'</TT> is not present, then the client creates it and forks
a new server for the cache.
<P>
The client creates <TT>`SOCKET'</TT> by opening it with the <CODE>O_CREAT</CODE> and
<CODE>O_EXCL</CODE> flags.
If two or more clients are started simultaneously on a cache with no
servers, and all attempt to create <TT>`SOCKET'</TT>, this combination of flags
ensures that only one of the create operations can succeed.
Thus one of the clients will create the socket file and fork the server,
while the file creation will fail on the others.
After the client has determined that a server is present, or
after its file creation fails, or
after it has successfully forked a server,
it connects to the socket defined by the cache's <TT>`SOCKET'</TT> file.
<P>
<H2><A NAME="SEC19" HREF="sysadmin_toc.html#SEC19">Execution scenarios</A></H2>
<P>
The simplest execution scenario involves a single person working on a
single computer.
There may be a number of caches, representing different projects, but
normally the user will work with only one at a time.
One client process and one server process will be running whenever the user
is actually interacting with Odin.
<P>
A slightly more complex situation involves a team, all of whom run on the
same machine.
Again, the team may be working on several different projects so there may
be several caches.
More than one member of the team may, however, be working with a particular
cache at the same time.
In that case, there will be one server process associated with each active
cache, and one client process associated with each active user.
The server process will mediate all of the client requests on a particular
cache to guarantee atomicity.
If two clients' requests have products in common, each of those products
will only be built once because the server knows that once the product is
up-to-date it need not be rebuilt.
<P>
Students working on individual projects, using a collection of networked
computers with a shared file system, can treat the situation as though they
were running on a single machine.
A small problem is that if they do not specify a cache explicitly with the
<CODE>-c</CODE> parameter, they will have a distinct cache on each of the
machines they use.
In order to avoid this duplication, we advocate use of the <VAR>ODINVIEW</VAR>
environment variable to define a single default cache name
(see  <A HREF="sysadmin_2.html#SEC5">Name of the cache</A>).
<P>
The most complex scenario is exemplified by students working in teams
in a lab with multiple machines and a shared file system.
Presumably each team member is sitting at a different machine.
One student will start a client, resulting in a server running on that
student's machine.
Now a second student starts a client on a different machine,
but referring to the project's common cache.
At that point, one server and two clients are running.
The server and one of the clients are both running on the first student's
machine, and the other client is running on the second student's machine.
<P>
Having clients run on different machines improves performance.
Remember that the client is responsible for executing tools that are not
built into Odin, so running clients on different machines allows such tools
to operate in parallel.
Since much of the cost of a given derivation is the cost of running tools,
this is an important benefit.
Another way of executing tools on different machines is to use a
<VAR>BuildHosts</VAR> list
(see  <A HREF="sysadmin_5.html#SEC16">Client execution</A>).
<P>
An Odin server makes very heavy use of cache files, many of which are quite
small.
Experience has shown that there is a serious performance degradation when
the server must access the cache over the network.
Thus it is useful to run an Odin server on the computer where the files are
actually stored.
The educational computer laboratory again provides a good example: the
shared file system is often stored on a central computer that serves the
information to the workstations in the laboratory.
One could start a session for the desired cache on the central computer,
and simply leave that session open.
Subsequent sessions for that cache, started on workstations, would use the
server running on the central computer.
<P>
<H2><A NAME="SEC20" HREF="sysadmin_toc.html#SEC20">Socket implementation</A></H2>
<P>
Odin supports two socket implementations:
<A NAME="IDX50"></A>
unix internet (<CODE>AF_INET</CODE>) sockets and
<A NAME="IDX51"></A>
unix domain (<CODE>AF_UNIX</CODE>) sockets.
The default is <CODE>AF_INET</CODE>; <CODE>AF_UNIX</CODE> is used only if the
environment variable
<A NAME="IDX53"></A>
<A NAME="IDX52"></A>
<VAR>ODIN_LOCALIPC</VAR> is set to <CODE>1</CODE>.
<P>
<CODE>AF_INET</CODE> sockets can handle all of our execution scenarios
(see  <A HREF="sysadmin_5.html#SEC19">Execution scenarios</A>).
When the environment involves a file system shared by several
machines, however, <CODE>AF_UNIX</CODE> sockets can be used if and only if
all interactions with a given cache at a given time involve a single
machine.
This restriction imposes an intolerable burden on a team, because each
team member must find out whether a server is already running,
and if so which machine it is running on,
before they can start their own client.
It also makes execution of a server on a central machine and clients on
associated workstations impossible.
Thus <VAR>ODIN_LOCALIPC</VAR> should be set to <CODE>1</CODE> only if Eli will not
function otherwise.
<P>
The socket implementation is reflected in two cache files,
<A NAME="IDX55"></A>
<A NAME="IDX54"></A>
<TT>`SOCKET'</TT> and
<A NAME="IDX57"></A>
<A NAME="IDX56"></A>
<TT>`ENV'</TT>.
If the socket implementation is <CODE>AF_UNIX</CODE>, then <TT>`SOCKET'</TT> is the
actual socket on which the server is listening for client connections
rather than a text file
(see  <A HREF="sysadmin_5.html#SEC18">Interprocess communication</A>).
<P>
<TT>`ENV'</TT> stores the values of important environment variables
(including that of <VAR>ODIN_LOCALIPC</VAR>) that were in effect at the time
that the cache was created or last reset by a <CODE>-R</CODE> parameter
(see  <A HREF="sysadmin_2.html#SEC6">Packages in the cache</A>).
Thus a specific socket implementation technique is associated with each
cache individually.
That technique is used whenever a session begins on the cache;
it can be changed only by establishing the appropriate value of
<VAR>ODIN_LOCALIPC</VAR> and resetting the cache via the <CODE>-R</CODE> parameter.
<A NAME="IDX58"></A>
<A NAME="IDX59"></A>
<P>
Interprocess communication failures in Eli can occur in two contexts:
communication between client and server, and
communication between a client and a child running a command.
A failure to communicate between client and server almost always results in
the error report <CODE>Cannot connect to Odin server</CODE> when making the
system originally.
If there have been no other difficulties (e.g. stopping and restarting the
make, re-configuring, etc.), then you should try the following:
<P>
<PRE>
make clean
ODIN_LOCALIPC=1 make
</PRE>
<P>
Please report all instances in which setting <VAR>ODIN_LOCALIPC</VAR>=1 is
necessary to build the system
(see  <A HREF="sysadmin_6.html#SEC21">Problem Reporting</A>).
<P>
If you are able to build the system initially without setting
<VAR>ODIN_LOCALIPC</VAR>=1, but the report <CODE>Cannot connect to Odin server</CODE>
appears during normal operation, the problem is almost certainly that the
server has been killed before it had the chance to remove file
<TT>`SOCKET'</TT> from the cache.
Resetting the cache with either the <CODE>-r</CODE> or <CODE>-R</CODE> parameter should
fix this.
<P>
A failure to communicate between a client and a child running a command
usually results in the system simply locking up.
Lockups could also conceivably occur in the socket communication,
so it is important to try to eliminate that possibility.
If the parameter
<A NAME="IDX60"></A>
<CODE>-s</CODE> is given on the <CODE>eli</CODE> command line then only a single process,
acting as both the client and the server, is used.
The program still establishes the <TT>`SOCKET'</TT> file in the cache, but
sockets will remain unused if you don't start any other clients
on the same cache.
Any lockups that occur in this mode of operation <EM>cannot</EM> be due to
client/server interaction.
<P>
If the lockups are intermittent, be certain to make several test runs with
the <CODE>-s</CODE> command line parameter before concluding that client/server
interaction is the culprit.
<P>
<HR size=1 noshade width=600 align=left>
<P>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="sysadmin_4.html"><IMG SRC="gifs/prev.gif" ALT="Previous Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="sysadmin_6.html"><IMG SRC="gifs/next.gif" ALT="Next Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="sysadmin_toc.html"><IMG SRC="gifs/up.gif" ALT="Table of Contents" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT="">
<HR size=1 noshade width=600 align=left>
</TD>
</TR>
</TABLE>

</BODY></HTML>
